Create Work Request
Introduction
The REST API POST /api/v2/workrequest allows a work request from another application such as a CRM to generate a work request within Assetic.
Once the work request is created in Assetic then the workflow management within Assetic takes place to resolve the issue raised by the request.
Request Fields
The following is a list of the key fields that can be used when creating a request in Brightly Assetic.
| Field | Description | Type | Mandatory |
| RequestorId | The customer that lodged the request. Assetic resource GUID of the customer to assign the request (or set Requestor which will re-use or create new customer) | GUID | Conditional |
| Requestor | Identify customer by name or create new customer. Not required if RequestorId defined | Resource object | Conditional |
| Description | Short description of the request | Char(250) | Yes |
| WorkRequestSourceID | The request source. Typically use 3 - "External CRM". (1="PC or Notebook", 2="Email", 4="Mobile Device", 5="Phone Call",6="In Person") | Int | Yes |
| WorkRequestPriorityID | Request priority. Labelled as 'Any Immediate Risk?' in application front end | Int | No |
| Location | Description of defect location. If unknown use street address | Char(100) | Yes |
| WorkRequestPhysicalLocation | Address and descriptors of request location | Object | Yes |
| WorkRequestSpatialLocation | Spatial location of the issue if known, else the location will be derived from the address defined in WorkRequestPhysicalLocation | Object | No |
| SupportingInformation | Request details | Char (4000) | No |
| ComplexAssetId | Assign the asset to the request, uses internal GUID, not the user-friendly asset id. Not required if "AssetId" is set | GUID | No |
| AssetId | The user-friendly Asset Id. Not required if the "ComplexAssetId" is set | String | No |
|
ExternalIdentifier
|
An external identifier number | Char(200) | No |
| ReferenceNumber | An external reference number | Char(200) | No |
| FeedbackRequired | Is Feedback to the requestor required | Boolean | No |
| FeedbackMethodId | Method of feedback to the requestor (Preferred Method) 1= Phone, 2=Text, 3=Email, 5=Letter | Int | No |
| WorkRequestSubTypeID | The categorisation of the type of issue reported. | Int | No |
| AcknowledgeDueDate | Date acknowledgement of the issue is required by | Datetime | No |
| ReactiveInspectorId | Assign a resource to inspect and verify the request | GUID | No |
| ReactiveInspector | Use the user-friendly resource display name as an alternative to ReactiveInspectorId | Resource object | No |
| ReactiveInspectionDate | Set a date for the inspection to occur | Datetime | No |
| ResponsibleOfficerId | Assign a resource responsible for actioning or triaging the request. | GUID | No |
| ResponsibleOfficer | Use the user-friendly resource display name as an alternative to ResponsibleOfficerId | Resource object | No |
The Resource API GET /api/v2/resource may be used to get the GUID of a resource based on resource name, or alternatively check for the existence of the resource. Refer to the article Get Resources.
Resources
The list of all resources (contacts) is managed via the Assetic Admin module in 'System'->'Resource Management'. Each Resource has a unique system GUID which may be referenced when creating the work request for the following properties:
- RequestorId
- ReactiveInspectorId
- ResponsibleOfficerId
If the resource GUID is unknown the 'Display Name' (usually a concatenation of requestor name and company) is used to search the resource list.
For "ReactiveInspector" and "ResponsibleOfficer" the resource must exist, else the Work Request will not be created. The resource must have a Resource Type as per the table "Resource Type Field Requirements" below.
For the 'Requestor' property (i.e. the "Customer") a new resource is created in the Resource list should the Requestor display name not already exist in the contact list. If the Requestor is found then a new resource is not created.
For "Requestor" setting the Requestor 'Type' as 'Customer' ensures that the resource is appropriately tagged. By tagging the Requestor as a 'Customer' it ensures the customer doesn't not appear in pick lists that do not relate to customers. The Requestor Type is required as per the table "Resource Type Field Requirements" below and must be specified when creating a new requestor.
Resource Type Field Requirements
The following table lists the required Resource Type of a resource when assigning that resource to the listed Work Request fields. Note the the Resource can also be linked to an Assetic login (user) in which case the Resource Type is ignored.
| Work Request Field | User | Team | Customer | Contractor | Employee | Company | None |
| Requester | Y | Y | Y | ||||
| Reactive Inspector | Y | Y | Y | Y | Y | ||
| Responsible Officer | Y | Y | Y | Y |
Resource Name
If "DisplayName" is not defined then it will be generated from the first name, surname and company name in the format "{first name} {surname} ({company})". The DisplayName is limited to 100 characters, so if the generated name is greater than 100 characters the API will return an error. It is prudent therefore to ensure the "DisplayName" is set in the request payload rather than relying on it to be generated.
Existing Resource
For existing resources the Requestor details such as phone number and address are not updated should they differ from what is currently defined in the resource list. The current resource details will be used, and not what is defined in the API POST
Requestor object
When defining the Requestor object for a new Work Request the following properties are relevant:
| Field | Description | Type | Mandatory |
| DisplayName | If the resource already exists with this display name then it is sufficient to just use this property. If NULL the displayName a concatenation of the FirstName, Surname, and Company. | char(100) | Conditional |
| FirstName | First name of person | char(50) | Conditional |
| Surname | Family name of person | char(50) | Conditional |
| Company | Company. Not required unless both First Name and Surname are empty | char(100) | Conditional |
| Position | Role withing the company | String | Optional |
| Status | "Active" or "Inactive", use "Active" | String | Optional |
| Types | An array of "Requestor Types". (See below) | Array of Object | Conditional |
| ExternalID | An external reference number | String | Optional |
| Phone | Phone number | String | Optional |
| Mobile | Mobile phone number | String | Optional |
| Fax | Fax number | String | Optional |
| Email address | String | Optional | |
| AddressComment | General comment about address | String | Optional |
| Address | Address | Address object | Optional |
Requestor Type
Requestor type object has 2 properties 'Id' (Integer) and 'Type' (String).
| Id | Type |
| 2 | Team |
| 4 | Customer |
| 8 | Contractor |
| 16 | Employee |
| 32 | Company |
Work Request Physical Location
The physical location is the address details that describe where the defect is located.
WorkRequestPhysicalLocation is an object with the following attributes:
| Field | Description | Type | Mandatory |
| Address | Address | Object | Yes |
| OtherLocation | Additional descriptor of location | Char(255) | No |
| WhereLocation | Additional descriptor of location | Char(255) | No |
Address
Address is an object with the following attributes:
| Field | Description | Type | Mandatory |
| StreetNumber | Street number | Char(255) | No |
| StreetAddress | Street Name and Type | Char(255) | Yes |
| CitySuburb | City/Suburb | Char(255) | Yes |
| State | State | Char(255) | Yes |
| ZipPostcode | Zip/Postcode | Char(255) | No |
| Country | Country | Char(255) | Yes |
Work Request Spatial Location
The spatial location is a spatial co-ordinate centered on the defect location. It is a point and is useful for displaying the location in a map.
The object WorkRequestSpatialLocation has the following fields:
| Field | Description | Type | Mandatory |
| PointString | Spatial point. Coordinate sytem assumed to be EPSG 4326. This is used to show the defect location in the Assetic map window. If location is unknown use a dummy value of a local feature such as the administration building for your organisation. | WKT | Yes |
WorkRequestSubTypeId (Request Type)
The WorkRequestSubTypeId defines the Request Type field in the work request. To get a list of valid Id's the Assetic REST API endpoint GET /api/v2/workrequesttype is used.
The reponse GET /api/v2/workrequesttype from is a paginated list of the Request Types configured in the system. These types are user defined, so will differ from site to site. The response lists WorkRequestType and within each type is the list of WorkRequestSubType's. The Id to use for WorkRequestSubTypeId is the value for the "Id" field in the "WorkRequestSubType" list.
When a user views/edits the Request Type in the Assetic application the options displayed in the dropdown list are a concatenation of 3 fields in the following order:
1. Request Type Code. This is the 'Code' defined for the Request Type. In the API response from above this is the 'Code' field
2. A period (.) precedes the second field which is Subtype Code. In the API response from above this is the 'Code' field for the selected 'WorkRequestSubType' for the selected Request Type
3. The short description for the Request Type. In the API response from above this is the 'WorkRequestActivitySubType' field for the selected 'WorkRequestSubType' for the selected Request Type
WorkRequestPriorityID
The following table lists the options to use for WorkRequestPriorityID:
| WorkRequestPriorityID | Priority | Description |
| 1 | No Immediate Risk | No perceived immediate risk to people, the environment or the organisation |
| 2 | Safety | There is a potential immediate risk to the safety of others as a result of the reported defect |
| 3 | Environment | There is a potential immediate risk to the environment as a result of the reported defect |
| 4 | Organisation | There is a potential immediate risk to the organisation as a result of the reported defect |
Sample Payload
The following is the minimum payload required to create a work request
{ "Requestor": {"DisplayName":"Kevin Wilton","Types": [{"Id": 4}]}, "Description": "Short Description of request", "WorkRequestSourceId": 3,
"Location": "Collins Street Melbourne, Victoria", "WorkRequestPhysicalLocation": { "Address":{"StreetAddress": "Collins Street", "CitySuburb": "Melbourne", "State": "Victoria", "Country": "Australia"} } }
The following is a typical payload used to create a work request
{ "Requestor": { "FirstName":"Roger", "Surname":"Federer", "Types": [{"Id": 4}], "Mobile": "067 377 098" }, "Description": "Short Description of request", "WorkRequestSourceId": 3, "Location": "Outside front entrance", "ExternalIdentifier": "CRM 123", "SupportingInformation": "This is a more detailed description of the issue", "WorkRequestPriorityId": 1, "WorkRequestSubTypeId": 2, "ReactiveInspector": { "DisplayName": "Rafael Nadal", }, "ReactiveInspectionDate": "2019-01-05T13:00:00", "WorkRequestPhysicalLocation": { "Address": { "StreetNumber": "Level 12, 257", "StreetAddress": "Collins Street", "CitySuburb": "Melbourne", "State": "Victoria", "ZipPostcode": "3000", "Country": "Australia" }, "OtherLocation": "Extra information - Other", "WhereLocation": "Extra information - Where", }, "WorkRequestSpatialLocation": { "PointString": "POINT (144.9651119 -37.8162149)" } }
Work Request Attachments
On successful POST of a Work Request, the response body for the request will return the GUID identifier of the created Work Request in String format. This Work Request GUID can be used for additional follow-up requests to the Assetic REST API in order to create and link documents against the Work Request.
This is achieved by supplying the Work Request's GUID for the 'ParentId' parameter, and by also providing the value "WorkRequest" for the 'ParentType' parameter within the payload for a request to the POST/api/v2/document endpoint.
Additional information covering the construction of a payload Document request, and how to upload files using the Assetic REST API Documents endpoint is covered in the article Uploading Files.
